Related Topics
CAUTION: The Q-SYS External Control Protocol, or its functional details, may change from release to release. Please be sure to check the Release Notes before installing subsequent releases of Q-SYS Designer. QSC is not responsible for the compatibility of your code with the Q-SYS External Control Protocol.
This topic describes the protocol for controlling a Q-SYS Core in Run Mode using TCP/IP on port 1702.
IMPORTANT: Please read the External Control Overview and Making Controls Available for External Control first.
IMPORTANT: An External Control client must communicate with the Q-SYS Core at least once every 60 seconds, or the socket connection will be closed by the Core. This is a form of "keep-alive" to make sure that abandoned connections get reclaimed by the Core. Most client programs poll a Change Group at a much higher rate which serves as a keep-alive. If not, the client program can issue a "Status Get" command periodically, or a "Control Set Value" on an unused control if no return response is desired.
VIDEO TUTORIAL: Video tutorial available online for External Control.
Messages in the protocol are ASCII, composed of the following basic types of data.
|
Data Type |
Definition |
|---|---|
|
Beginning of message |
There is no beginning of message indicator in the protocol. White space is discarded after the previous null character and the first non-whitespace character is assumed to be the beginning the next message. |
|
End of message (EOM) |
All commands and responses end with the End of Message (EOM) character. The EOM character is <LF> (0x0A). The Core waits until the EOM is received before parsing and executing the command. The Core will ignore a <CR> (0x0D) character if it precedes the EOM. (This allows the use of telnet for debugging because telnet generates <CR><LF> when you press the Enter key.) The Core terminates all responses with <CR><LF>. (This makes the responses readable when using telnet for debugging, but it also means the client must ignore the <CR> character.) If a command contains extra arguments before the EOM, a "bad_command" error will be returned. cg text extra -> bad_command "expected EOM" If a string argument contains the <LF> character, it must be encoded as "\n" (the character back slash followed by the character n) If a string argument contains the <CR> character, it must be encoded as "\r" (the character back slash followed by the character r) cg text -> cv "text" "" 0 0 css text "multi\r\nline" <-- in the GUI this will show up as 2 lines -> cv "text" "multi\r\nline" 0 0 |
|
unsigned integer |
Whole number between 0 and 4294967294 inclusive |
|
floating point number |
32 -bit floating point number |
|
string |
Sequence of ASCII characters. Since arguments are separated by spaces, strings containing spaces must be enclosed in double quotation marks. If the string contains a quotation mark, the quotation mark must be escaped (preceded) with a back slash. If the string contains a back slash, the back slash must be escaped with another back slash. If the string contains the line feed character (0x0A) it must be encoded as back slash n. If the string contains the carriage return character (0x0D), it must be encoded as back slash r. |
The following arguments are used in commands. All arguments are separated by spaces. In order to reduce network traffic, it is suggested that you use short numbers and names for the arguments.
|
Argument Name |
Data Type |
Definition |
|---|---|---|
|
Command string |
string |
This is the short string that begins each message. It indicates what action is to take place. None contain spaces and they do not need to be enclosed in quotation marks. Command strings are case sensitive. |
|
Response string |
string |
This the short string that begins a response to a command message. |
|
CONTROL_ID |
string |
Identifies a control as defined as a Named Control in Q-SYS Designer. You must make the control available for external control to be used. |
|
CONTROL_VALUE |
floating point number |
Represents the numerical value of a control. The range of this number depends on the particular control. |
|
CONTROL_POSITION |
floating point number |
Between 0.00 and 1.0 inclusive. Indicates where the value lies within the range of the control. Subject to a mapping. |
|
CONTROL_STRING |
string |
Contains the textual representation of a control's state such as "-2.3 dB" or "3.45 kHz" |
|
COUNT |
unsigned integer |
Indicates the count of elements that follow. |
|
CHANGE_GROUP_ID |
unsigned integer |
Identifies a Change Group. This identifier is scoped to the connection that created it so it is not a problem if two clients each create groups with the same identifier. Also, a client cannot open two sockets to the Core, create a Change Group on one socket and poll it on the other. You can create up to four Change Groups, and poll the groups at separate rates. |
|
DESIGN_ID |
string |
A unique ID given to a design every time it is compiled or emulated. |
|
DESIGN_NAME |
string |
The name of the design currently running on the Core. |
|
IS_ACTIVE |
unsigned integer |
Is a 1 if this is the active Core of a redundant pair or the design is not redundant, 0 if it is not active |
|
IS_PRIMARY |
unsigned integer |
Is a 1 if this is the primary Core of a redundant pair, or the design is not redundant, 0 otherwise |
|
NAME |
string |
The user name assigned to an external control system. The name is assigned in the Q-SYS Administrator, User tab. |
|
PIN |
string |
Size is unlimited. The personal identification number assigned to a User along with the NAME. The User must have privileges enabledfor external control. The PIN is assigned in the Q-SYS Administrator, User tab. |
|
RAMP_TIME_SEC |
floating point number |
Used as an argument in Snapshot Load for the ramp time in seconds. |
|
string |
Identifies a bank of Snapshots. This is the name given to the bank when it was created in Q-SYS Designer. |
|
|
SNAPSHOT_NUMBER |
unsigned integer |
Identifies a snapshot within a snapshot bank. The range is 1 to the number of snapshots in the bank, inclusive. |
|
POLL_PERIOD_MS |
unsigned integer |
Used as an argument in Change Group Schedule for the poll period in milliseconds. |
|
Command Title |
Command String |
Syntax |
Response |
|---|---|---|---|
|
cga |
cga CHANGE_GROUP_ID CONTROL_ID |
none bad_change_group_handle bad_id |
|
|
cgclr |
cgclr CHANGE_GROUP_ID |
none bad_change_group_handle |
|
|
cgc |
cgc CHANGE_GROUP_ID |
none bad_change_group_handle |
|
|
cgd |
cgd CHANGE_GROUP_ID |
none bad_change_group_handle |
|
|
cgi |
cgi CHANGE_GROUP_ID |
none The next Change Group Poll, returns all the controls, including their: values, positions, and so on. |
|
|
cgp |
cgp CHANGE_GROUP_ID |
cv cmvv cgpa bad_change_group_handle |
|
|
cgpna |
cgpna CHANGE_GROUP_ID |
cv cmvv bad_change_group_handle |
|
|
cgr |
cgr CHANGE_GROUP_ID CONTROL_ID |
none bad_change_group_handle bad_id After a control has been removed from a Change Group, it may still be returned from the next polling. |
|
|
cgs |
cgs CHANGE_GROUP_ID POLL_PERIOD_MS |
none bad_change_group_handle Based on the schedule, a |
|
|
cgsna |
cgsna CHANGE_GROUP_ID POLL_PERIOD_MS |
none bad_change_group_handle |
|
|
cg |
cg CONTROL_ID |
cv cvv bad_id |
|
|
cgm |
cgm CONTROL_ID |
cmv cmvv bad_id zero or more |
|
|
csp |
csp CONTROL_ID CONTROL_POSITION |
cv bad_id |
|
|
cspr |
cspr CONTROL_ID CONTROL_POSITION RAMP_TIME |
|
|
|
cspv |
cspv CONTROL_ID NUM_POSITIONS CONTROL_POS1 CONTROL_POS2 CONTROL_POS3…CONTROL_POSx |
|
|
|
cspvr |
cspv CONTROL_ID NUM_POSITIONS CONTROL_POSITION1 CONTROL_POS2.. CONTROL_POSx RAMP_TIME |
|
|
|
css |
css CONTROL_ID CONTROL_STRING |
cv bad_id |
|
|
cssv |
cssv CONTROL_ID NUM_STRINGS CONTROL_STRING1 CONTROL_STRING2 CONTROL_STRING3…CONTROL_STRINGx |
|
|
|
csv |
csv CONTROL_ID CONTROL_VALUE |
|
|
|
csvr |
csvr CONTROL_ID CONTROL_VALUE RAMP_TIME |
|
|
|
csvv |
csvv CONTROL_ID NUM_VALUES CONTROL_VALUE1 CONTROL_VALUE2.. CONTROL_VALUEx |
|
|
|
csvvr |
csvvr CONTROL_ID CONTROL_VALUE1 CONTROL_VALUE2 CONTROL_VALUE3…CONTROL_VALUExRAMP_TIME |
|
|
|
ct |
ct CONTROL_ID |
|
|
|
login |
login NAME PIN |
An attempt to access a Core that requires an external control system to login, receives a |
|
|
ssl |
ssl SNAPSHOT_BANK SNAPSHOT_NUMBER FLOATING_POINT_NUMBER |
none |
|
|
sss |
sss SNAPSHOT_BANK SNAPSHOT_NUMBER |
none |
|
|
sg |
sg |
sr |
|
Response Title |
Response String |
Syntax |
Response To |
|---|---|---|---|
|
cgpa |
cgpa |
cgp |
|
|
cmv |
cmv CONTROL_ID metadata_aspec CONTROL_STRING CONTROL_VALUE CONTROL_POSITION |
cgm |
|
|
cmvv |
cmvv CONTROL_ID metadata_aspec COUNT CONTROL_STRING ... COUNT CONTROL_VALUE ... COUNT CONTROL_POSITION ... |
cgm |
|
|
core_read_only |
cro <CONTROL_ID> |
csp css csv |
|
|
cv |
cv CONTROL_ID CONTROL_STRING CONTROL_VALUE CONTROL_POSITION |
cgp cg csp css |
|
|
cvv |
cvv CONTROL_ID COUNT CONTROL_STRING ... COUNT CONTROL_VALUE ... COUNT CONTROL_POSITION ... |
cg |
|
|
core_not_active |
core_not_active |
csp css csv ssl sss ct |
|
|
bad_change_group_handle |
bad_change_group_handle CHANGE_GROUP_ID |
cga cgclr cgc cgd cgp cgr cgs |
|
|
bad_command |
bad_command STRING |
Any command |
|
|
bad_id |
bad_id CONTROL_ID |
cga cgr cg cgm csp css ct |
|
|
Login Failed |
login_failed |
login_failed |
login |
|
Login Required |
login_required |
login_required |
Attempt to access a Core that requires a login. |
|
Login Success |
login_success |
login_success |
login |
|
sr |
sr DESIGN_NAME DESIGN_ID IS_PRIMARY IS_ACTIVE |
sg |
|
|
too_many_change_groups |
too_many_change_groups |
cgc |
IMPORTANT: Please read the External Control Overview, Change Groups section for information about change groups.
CHANGE_GROUP_ID is a 32-bit unsigned integer, however, it is recommended that you use smaller numbers to reduce network traffic. The bad_change_group_handle response is returned if you attempt to create more than four. This command is "silently" ignored if you attempt to create a Change Group with a CHANGE_GROUP_ID that is already in use. For more information on Change Groups refer to Change Groups in the External Control Overview.cgpa response is sent at the end of the response, or by itself if nothing in the Change Group has changed.cgpa response is not sent.cgp.POLL_PERIOD_MS argument is an unsigned integer for the poll period in milliseconds. Minimum for POLL_PERIOD_MS is 30 ms, any amount less than this is changed to 30 ms. To turn off the scheduling of a group, enter 0 (zero) for POLL_PERIOD_MS. To change the schedule, issue this command with a new POLL_PERIOD_MS.cgp will be sent.POLL_PERIOD_MS argument is an unsigned integer for the poll period in milliseconds. Minimum for POLL_PERIOD_MS is 30 ms, any amount less than this is changed to 30 ms. To turn off the scheduling of a group, enter 0 (zero) for POLL_PERIOD_MS. To change the schedule, issue this command with a new POLL_PERIOD_MS.cgp, a cgpna is issued, so there is no cgpa sent.A Vector Control has multiple strings, values and positions at a time, for example, a meter bar. A meter displays RMS, Max RMS, Peak, and Max Peak values. The Control Get command (cg) returns Control Vector Value response (cvv) when the control is a vector type control. You cannot set the values of a Vector Control.
NOTE: For a Meter component, the strings, values, and positions are RMS, Max RMS, Peak, and Max Peak, in that order.
NOTE: cspr does not return a “cv” response of the final value. To check the value after a ramp has completed use the “cg” command.
NOTE: csvr does not return a cv response of the final value. To check the value after a ramp has completed the cg command should be used.
NAME and PIN arguments must be for a valid User, with the appropriate permissions, existing in the Q-SYS System. If an attempt is made to login, without a NAME and PIN, to a system requiring login, a login_required response is sent. If a login_failed response is sent, the socket is automatically closed.RAMP_TIME_LOAD argument is a floating point number for the load ramp time in seconds.cgpa response is sent at the end of a response, and by itself if nothing in the Change Group has changed. cgp
cgm or cgp|
Value |
Name |
Description |
|---|---|---|
|
0 |
metadata_aspect_none |
Should never appear. |
|
1 |
metadata_aspect_range |
Minimum and maximum value as in a 2-element floating-decimal vector control |
|
2 |
metadata_aspect_choices |
An array of strings |
|
3 |
metadata_aspect_color |
A string describing the color of the control. Used when a Custom control is in a not-normal state, for example, grayed out. |
|
4 |
metadata_aspect_indeterminant |
Boolean control, position > 0.5 indicates the control represents an unknown value, or represents multiple different values simultaneously. |
|
5 |
metadata_aspect_invisible |
Boolean control, position > 0.5 means the control is invisible and should not be displayed because it is irrelevant in the current context. For example, a bandwidth control on a high-shelf equalizer. |
|
6 |
metadata_aspect_disabled |
Boolean control, position > 0.5 means grayed / disabled. |
|
7 |
metadata_aspect_legend |
String control, specifies the legend drawn on buttons |
Metadata means "data about data". In Q-SYS, some controls have metadata attached that describe aspects of the control. These aspects can include the range of the control, its color, whether it is disabled or invisible or its value is indeterminate, or a list of legal values for the control.
As an example, consider the Crossover component. The Slope, Type and Bessel Normalization controls all have metadata that describe the choices available in the drop-down list. The Bessel Normalization control also has metadata to make it invisible when the filter type is not Bessel-Thomson. When a Link button is pressed, all of the controls on the high frequency side of the crossover point are disabled through the use of metadata.
When you ask a control for its metadata with cgm (Control Get Metadata), you get a response for each aspect of metadata attached to that control, if any. The response is either cmv (Control Metadata Value) or cmvv (Control Metadata Value Vector). These responses look very similar to the responses you get when asking for a control's state with cg (Control Get), this is because the metadata is very much like a control itself in that is has a value, a position and a string. The only difference between the cv (Control Value) response and the cmv (Control Metadata Value) response is that cmv has the extra unsigned integer second argument that identifies which aspect of metadata is being described. Similarly the only difference between cvv (Control Value Vector) and cmvv (Control Metadata Value Vector) is the same additional argument.
cg command: cv "slope" "48dB/Oct" 48 1cgm command: cmvv "slope" 2 4 "12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" 0 0 |
Control Metadata Value Vector Response Breakdown |
|
|---|---|
|
Response |
Description |
|
slope |
The CONTROL_ID |
|
2 |
The |
|
4 |
The COUNT of the "strings" following
"12 dB/Oct" "24 dB/Oct" "36 dB/Oct" "48 dB/Oct" |
|
0 |
The COUNT of the "values" following (in this case, none) |
|
0 |
The COUNT of the "positions" following (in this case, none) |
cg command: cv "ssload" "" 0 0cgm command: cmv "ssload" 6 "false" 0 0|
Control Metadata Value Response Breakdown |
|
|---|---|
|
Response |
Description |
|
ssload |
The CONTROL_ID |
|
6 |
The |
|
false |
The string describing the state of the control. |
|
0 |
The "value" of the control |
|
0 |
The "position" of the control |
cgm or cgp. See Control Get Metadata for details.cgm or cgpcsp, css, csv) is performed on a read-only control. csp, css, or csvcss, csv, csp, cg, and cgp.cg
NOTE: For a Meter component, the strings, values, and positions are current reading and Max reading. The readings change from RMS to Peak depending on the Peak/RMS switch on the meter.
csp, css, csv), Snapshot Load command (ssl, sss), or Control Trigger (ct) is performed on the standby Core of a redundant pair.csp, css, csv, sslsss, ctcore_not_active
CHANGE_GROUP_ID.CHANGE_GROUP_ID argument that is not recognized.NOTE: The "CG" command in the example below is not recognized because the commands are all lower case, and case sensitive.
CONTROL_ID argument is not recognized.CONTROL_ID argument that is not recognized.NOTE: The "load3" command in the example below is not valid because it does not exist.
|
Argument |
Data Type |
Description |
|---|---|---|
|
DESIGN_NAME |
string |
The name with which the currently running design file was saved. |
|
DESIGN_ID |
string |
A unique string generated every time a Design is deployed to a Core, or pair of Cores, or when the Design is emulated. |
|
IS_PRIMARY |
unsigned integer |
Is a 1 if this is the primary Core of a redundant pair, or the design is not redundant, 0 otherwise |
|
IS_ACTIVE |
unsigned integer |
Is a 1 if this is the active Core of a redundant pair or the design is not redundant, 0 if it is not active |
cgc) is called and four change groups have already been created on the connection, or the total count of 256 change groups system wide would be exceeded with this command.cgc
© 2009 - 2016 QSC, LLC. All rights reserved. QSC and the QSC logo are trademarks of QSC, LLC in the U.S. Patent and Trademark office and other countries. All other trademarks are the property of their respective owners.
http://patents.qsc.com.
